OpenManus 使用指南

从安装配置到实践操作的完整指南

本章概览

环境安装：conda 和 uv 两种方式
配置详解：LLM、浏览器、搜索、MCP
三种运行模式：main.py、run_flow.py、run_mcp.py
实战案例：从简单到复杂的使用场景
最佳实践：使用技巧与注意事项

1. 环境安装

1.1 系统要求

要求	说明
操作系统	macOS, Linux, Windows
Python	3.12+
内存	建议 8GB+
网络	需要访问 OpenAI API

1.2 方式一：使用 conda

bash

# 1. 创建虚拟环境
conda create -n open_manus python=3.12
conda activate open_manus

# 2. 克隆仓库
git clone https://github.com/FoundationAgents/OpenManus.git
cd OpenManus

# 3. 安装依赖
pip install -r requirements.txt

# 4. 可选：安装浏览器驱动（用于浏览器自动化）
playwright install

1.3 方式二：使用 uv（推荐）

uv 是一个快速的 Python 包管理器：

bash

# 1. 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 克隆仓库
git clone https://github.com/FoundationAgents/OpenManus.git
cd OpenManus

# 3. 创建虚拟环境
uv venv --python 3.12
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# 4. 安装依赖
uv pip install -r requirements.txt

# 5. 可选：安装浏览器驱动
playwright install

为什么推荐 uv？

                pip                          uv
┌─────────────────────────────┐  ┌─────────────────────────────┐
│                             │  │                             │
│  安装 50 个包：~2 分钟       │  │  安装 50 个包：~10 秒        │
│                             │  │                             │
│  依赖解析：串行             │  │  依赖解析：并行              │
│                             │  │                             │
│  缓存管理：基础             │  │  缓存管理：智能              │
│                             │  │                             │
└─────────────────────────────┘  └─────────────────────────────┘

1.4 验证安装

bash

# 检查 Python 版本
python --version
# Python 3.12.x

# 检查核心依赖
python -c "import openai; import pydantic; print('OK')"
# OK

# 检查浏览器驱动（可选）
python -c "from playwright.sync_api import sync_playwright; print('Playwright OK')"

2. 配置详解

2.1 配置文件结构

bash

# 复制配置模板
cp config/config.example.toml config/config.toml

配置文件结构：

config/
├── config.toml          # 主配置文件
├── config.example.toml  # 配置模板
└── mcp.json            # MCP 服务器配置

2.2 LLM 配置

toml

# config/config.toml

# 全局 LLM 配置（默认配置）
[llm]
model = "gpt-4o"                       # 使用的模型
base_url = "https://api.openai.com/v1" # API 地址
api_key = "sk-..."                     # API 密钥
max_tokens = 4096                      # 最大输出 token
temperature = 0.0                      # 温度（0=确定性，1=随机）
api_type = "openai"                    # API 类型：openai/azure/aws

# 可选：限制总输入 token（控制成本）
# max_input_tokens = 100000

# 可选：特定用途的模型配置（覆盖默认值）
[llm.vision]
model = "gpt-4o"
max_tokens = 8192

[llm.fast]
model = "gpt-4o-mini"
temperature = 0.5

支持的模型提供商：

提供商	api_type	说明
OpenAI	`openai`	直接使用 OpenAI API
Azure OpenAI	`azure`	需要额外配置 api_version
AWS Bedrock	`aws`	使用 AWS 托管的模型
其他兼容 API	`openai`	如 OpenRouter、本地 LLM

使用 OpenRouter 示例：

toml

[llm]
model = "anthropic/claude-3-sonnet"
base_url = "https://openrouter.ai/api/v1"
api_key = "sk-or-..."

2.3 浏览器配置

toml

[browser]
# 是否使用无头模式（false = 可见浏览器窗口）
headless = false

# 禁用安全限制（允许跨域等）
disable_security = true

# 内容提取最大长度
max_content_length = 2000

# 可选：使用已有的 Chrome 实例
# chrome_instance_path = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

# 可选：连接远程浏览器
# wss_url = "wss://..."
# cdp_url = "http://localhost:9222"

# 可选：代理设置
[browser.proxy]
server = "http://proxy.example.com:8080"
username = "user"
password = "pass"

2.4 搜索配置

toml

[search]
# 主搜索引擎
engine = "Google"

# 备用搜索引擎（按顺序尝试）
fallback_engines = ["DuckDuckGo", "Bing", "Baidu"]

# 所有引擎失败后的重试延迟（秒）
retry_delay = 60

# 最大重试次数
max_retries = 3

# 搜索语言和地区
lang = "zh"
country = "cn"

2.5 MCP 配置

MCP 服务器在单独的 JSON 文件中配置：

json

// config/mcp.json
{
    "mcpServers": {
        "filesystem": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@anthropic/mcp-server-filesystem", "/path/to/allowed/dir"]
        },
        "custom-server": {
            "type": "sse",
            "url": "http://localhost:8080/mcp"
        }
    }
}

MCP 连接类型：

类型	说明	适用场景
`stdio`	通过标准输入输出通信	本地命令行工具
`sse`	通过 HTTP SSE 通信	远程服务、Web 服务

2.6 沙箱配置

toml

[sandbox]
# 是否启用沙箱（Docker 容器隔离）
use_sandbox = false

# 沙箱镜像
image = "python:3.12-slim"

# 容器工作目录
work_dir = "/workspace"

# 资源限制
memory_limit = "512m"
cpu_limit = 1.0

# 命令超时（秒）
timeout = 300

# 是否允许网络访问
network_enabled = false

2.7 多 Agent 流程配置

toml

[runflow]
# 启用数据分析 Agent
use_data_analysis_agent = true

3. 三种运行模式

3.1 基础模式：main.py

最简单的运行方式，启动单个 Manus Agent：

bash

python main.py

交互流程：

$ python main.py
Enter your prompt: 帮我搜索今天的科技新闻

Processing your request...
✨ Manus's thoughts: 我将使用网络搜索工具查找科技新闻...
🛠️ Manus selected 1 tools to use
🧰 Tools being prepared: ['web_search']
...
Request processing completed.

命令行参数：

bash

# 直接传入 prompt
python main.py --prompt "计算 1+1 的结果"

3.2 规划模式：run_flow.py

使用 PlanningFlow 执行复杂任务：

bash

python run_flow.py

规划模式的特点：

自动将大任务分解为步骤
按顺序执行每个步骤
可以使用多个 Agent 协作

示例交互：

$ python run_flow.py
Enter your prompt: 分析这个 CSV 文件并生成可视化报告

Processing your request...
Plan: 分析 CSV 并生成报告 (ID: plan_1234567)
==========================================
Progress: 0/4 steps completed (0.0%)

Steps:
0. [ ] 读取和理解 CSV 文件结构
1. [ ] 数据清洗和预处理
2. [ ] 统计分析和洞察
3. [ ] 生成可视化图表

Executing step 0...

3.3 MCP 模式：run_mcp.py

连接 MCP 服务器，扩展工具能力：

bash

python run_mcp.py

MCP 模式流程：

1. 读取 config/mcp.json
2. 连接所有配置的 MCP 服务器
3. 注册服务器提供的工具
4. 启动增强版 Manus Agent

4. 实战案例

4.1 案例一：网络搜索与信息整理

任务：搜索并整理 AI Agent 框架的对比信息

Enter your prompt: 搜索 2024 年最流行的 5 个 AI Agent 框架，对比它们的特点

Agent 执行过程：

Step 1: WebSearch - 搜索 "top AI Agent frameworks 2024"
Step 2: BrowserUseTool - 访问搜索结果页面
Step 3: BrowserUseTool - 提取页面内容
Step 4: 整理对比信息
Step 5: Terminate - 返回结果

最终输出：

根据搜索结果，2024 年最流行的 5 个 AI Agent 框架：

1. LangChain
   - 特点：生态丰富，组件化设计
   - 适用：快速原型开发

2. AutoGPT
   - 特点：完全自主，任务分解能力强
   - 适用：复杂长期任务

3. MetaGPT
   - 特点：多角色协作，软件开发专注
   - 适用：代码生成

4. OpenManus
   - 特点：简洁实现，工具集成丰富
   - 适用：通用任务自动化

5. CrewAI
   - 特点：团队协作模式，角色定义灵活
   - 适用：多 Agent 场景

4.2 案例二：代码生成与执行

任务：编写并运行一个数据分析脚本

Enter your prompt: 用 Python 生成 100 个随机数，计算平均值和标准差，并画一个直方图

Agent 执行过程：

python

# Step 1: PythonExecute - 生成代码
import numpy as np
import matplotlib.pyplot as plt

# 生成 100 个随机数
data = np.random.randn(100)

# 计算统计量
mean = np.mean(data)
std = np.std(data)
print(f"平均值: {mean:.4f}")
print(f"标准差: {std:.4f}")

# 绘制直方图
plt.figure(figsize=(10, 6))
plt.hist(data, bins=20, edgecolor='black')
plt.axvline(mean, color='red', linestyle='--', label=f'Mean: {mean:.2f}')
plt.title('Random Numbers Distribution')
plt.xlabel('Value')
plt.ylabel('Frequency')
plt.legend()
plt.savefig('histogram.png')
print("图表已保存为 histogram.png")

输出：

平均值: 0.0523
标准差: 0.9847
图表已保存为 histogram.png

4.3 案例三：浏览器自动化

任务：自动填写网页表单

Enter your prompt: 访问 example.com/form，填写姓名为"张三"，邮箱为"test@example.com"，然后提交

Agent 执行过程：

Step 1: browser_use(action="go_to_url", url="https://example.com/form")
        → 导航到表单页面

Step 2: browser_use(action="input_text", index=1, text="张三")
        → 填写姓名字段

Step 3: browser_use(action="input_text", index=2, text="test@example.com")
        → 填写邮箱字段

Step 4: browser_use(action="click_element", index=5)
        → 点击提交按钮

Step 5: browser_use(action="extract_content", goal="确认提交成功")
        → 验证结果

4.4 案例四：多步骤文件操作

任务：创建并修改配置文件

Enter your prompt: 在 workspace 目录创建一个 config.yaml 文件，写入数据库配置，然后修改端口为 5432

Agent 执行过程：

Step 1: str_replace_editor(command="create", path="/workspace/config.yaml", file_text="...")
        → 创建文件

Step 2: str_replace_editor(command="view", path="/workspace/config.yaml")
        → 查看文件内容

Step 3: str_replace_editor(command="str_replace", path="...", old_str="port: 3306", new_str="port: 5432")
        → 修改端口

文件内容：

yaml

# config.yaml
database:
  host: localhost
  port: 5432  # 已修改
  name: myapp
  user: admin

5. 最佳实践

5.1 Prompt 编写技巧

好的 Prompt：

✅ 具体明确：
"在 /workspace 目录创建一个 Python 脚本，实现斐波那契数列前 20 项的计算，并保存到 fib.py"

✅ 分步描述：
"1. 搜索今天的 Python 新闻
   2. 选择最热门的 3 条
   3. 整理成 Markdown 格式"

✅ 包含约束条件：
"用 pandas 分析 data.csv，统计每列的缺失值比例，不要修改原文件"

不好的 Prompt：

❌ 过于模糊：
"帮我处理一下这个"

❌ 缺少上下文：
"继续上次的任务"（Agent 没有历史记忆）

❌ 多个无关任务：
"搜索新闻，顺便帮我订个机票，再看看股票"

5.2 资源管理

控制 Token 用量：

toml

[llm]
max_input_tokens = 50000  # 限制总输入 token
max_tokens = 2048         # 限制单次输出

监控执行步骤：

python

# 设置合理的最大步骤数
class Manus(ToolCallAgent):
    max_steps: int = 20  # 默认值，可根据任务调整

5.3 错误处理

常见错误及解决方案：

错误	原因	解决方案
`API key not found`	未配置 API 密钥	检查 config.toml
`Token limit exceeded`	上下文过长	减少历史消息或增加限制
`Tool not found`	工具名称错误	检查 available_tools
`Browser timeout`	页面加载慢	增加超时或检查网络
`MCP connection failed`	服务器未启动	检查 mcp.json 配置

5.4 调试技巧

启用详细日志：

python

# 在代码中设置日志级别
import logging
logging.basicConfig(level=logging.DEBUG)

观察 Agent 思考过程：

✨ Manus's thoughts: 我需要先搜索相关信息...
🛠️ Manus selected 1 tools to use
🧰 Tools being prepared: ['web_search']
🔧 Tool arguments: {"query": "Python news today"}
🎯 Tool 'web_search' completed! Result: ...

5.5 安全建议

API 密钥保护：

bash

# 使用环境变量
export OPENAI_API_KEY="sk-..."

# 配置文件中引用
# api_key = "${OPENAI_API_KEY}"

沙箱隔离：

toml

[sandbox]
use_sandbox = true
network_enabled = false  # 禁用网络访问

工作目录限制：

python

# 只允许访问 workspace 目录
workspace_root = PROJECT_ROOT / "workspace"

6. 进阶用法

6.1 自定义 Agent

python

# custom_agent.py
from app.agent.toolcall import ToolCallAgent
from app.tool import ToolCollection, PythonExecute, Terminate

class MyCustomAgent(ToolCallAgent):
    name: str = "MyAgent"
    description: str = "专门处理数学计算的 Agent"

    system_prompt: str = """
    你是一个数学专家。只使用 Python 代码解决数学问题。
    始终显示计算过程和结果。
    """

    available_tools: ToolCollection = ToolCollection(
        PythonExecute(),
        Terminate(),
    )

    max_steps: int = 10

6.2 自定义工具

python

# custom_tool.py
from app.tool.base import BaseTool, ToolResult

class WeatherTool(BaseTool):
    name: str = "get_weather"
    description: str = "获取指定城市的天气信息"

    parameters: dict = {
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "城市名称",
            },
        },
        "required": ["city"],
    }

    async def execute(self, city: str) -> ToolResult:
        # 实际实现中调用天气 API
        weather_info = f"{city}: 晴天，温度 25°C"
        return ToolResult(output=weather_info)

6.3 扩展 PlanningFlow

python

# custom_flow.py
from app.flow.planning import PlanningFlow

class CustomPlanningFlow(PlanningFlow):
    async def _create_initial_plan(self, request: str) -> None:
        # 自定义计划创建逻辑
        await super()._create_initial_plan(request)

        # 添加额外的验证步骤
        await self.planning_tool.execute(
            command="update",
            plan_id=self.active_plan_id,
            steps=self.planning_tool.plans[self.active_plan_id]["steps"] + ["验证结果"],
        )

7. 常见问题 FAQ

Q1: OpenManus 支持哪些 LLM？

A: 任何兼容 OpenAI API 格式的模型都可以使用，包括：

OpenAI GPT-4o, GPT-4, GPT-3.5
Azure OpenAI
AWS Bedrock (Claude)
本地模型（通过 LiteLLM、Ollama 等）
OpenRouter 托管的各种模型

Q2: 如何降低 API 费用？

A: 几种方法：

使用 gpt-4o-mini 替代 gpt-4o
设置 max_input_tokens 限制总用量
减少 max_steps 避免过长执行
使用本地模型（如 Ollama + Llama）

Q3: 浏览器自动化为什么失败？

A: 常见原因：

未安装 Playwright：playwright install
页面有反爬虫机制
元素索引错误（页面 DOM 变化）
网络超时

Q4: 如何处理中文输入？

A: OpenManus 完全支持中文：

toml

[search]
lang = "zh"
country = "cn"

Q5: 任务执行中断怎么办？

A: 当前版本不支持断点续传。建议：

将大任务拆分为小任务
使用 PlanningFlow 自动分步
保存中间结果到文件

下一章：22.6 总结与展望 - 项目评价与未来方向

OpenManus 使用指南 ​

本章概览 ​

1. 环境安装 ​

1.1 系统要求 ​

1.2 方式一：使用 conda ​

1.3 方式二：使用 uv（推荐） ​

1.4 验证安装 ​

2. 配置详解 ​

2.1 配置文件结构 ​

2.2 LLM 配置 ​

2.3 浏览器配置 ​

2.4 搜索配置 ​

2.5 MCP 配置 ​

2.6 沙箱配置 ​

2.7 多 Agent 流程配置 ​

3. 三种运行模式 ​

3.1 基础模式：main.py ​

3.2 规划模式：run_flow.py ​

3.3 MCP 模式：run_mcp.py ​

4. 实战案例 ​

4.1 案例一：网络搜索与信息整理 ​

4.2 案例二：代码生成与执行 ​

4.3 案例三：浏览器自动化 ​

4.4 案例四：多步骤文件操作 ​

5. 最佳实践 ​

5.1 Prompt 编写技巧 ​

5.2 资源管理 ​

5.3 错误处理 ​

5.4 调试技巧 ​

5.5 安全建议 ​

6. 进阶用法 ​

6.1 自定义 Agent ​

6.2 自定义工具 ​

6.3 扩展 PlanningFlow ​

7. 常见问题 FAQ ​

Q1: OpenManus 支持哪些 LLM？ ​

Q2: 如何降低 API 费用？ ​

Q3: 浏览器自动化为什么失败？ ​

Q4: 如何处理中文输入？ ​

Q5: 任务执行中断怎么办？ ​

OpenManus 使用指南

本章概览

1. 环境安装

1.1 系统要求

1.2 方式一：使用 conda

1.3 方式二：使用 uv（推荐）

1.4 验证安装

2. 配置详解

2.1 配置文件结构

2.2 LLM 配置

2.3 浏览器配置

2.4 搜索配置

2.5 MCP 配置

2.6 沙箱配置

2.7 多 Agent 流程配置

3. 三种运行模式

3.1 基础模式：main.py

3.2 规划模式：run_flow.py

3.3 MCP 模式：run_mcp.py

4. 实战案例

4.1 案例一：网络搜索与信息整理

4.2 案例二：代码生成与执行

4.3 案例三：浏览器自动化

4.4 案例四：多步骤文件操作

5. 最佳实践

5.1 Prompt 编写技巧

5.2 资源管理

5.3 错误处理

5.4 调试技巧

5.5 安全建议

6. 进阶用法

6.1 自定义 Agent

6.2 自定义工具

6.3 扩展 PlanningFlow

7. 常见问题 FAQ

Q1: OpenManus 支持哪些 LLM？

Q2: 如何降低 API 费用？

Q3: 浏览器自动化为什么失败？

Q4: 如何处理中文输入？

Q5: 任务执行中断怎么办？